home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_1.3 / Autodocs1.3 / LibrariesA-K / icon.doc < prev    next >
Text File  |  1988-10-16  |  8KB  |  307 lines
  1. TABLE OF CONTENTS
  2.  
  3. icon.library/AddFreeList
  4. icon.library/BumpRevision
  5. icon.library/FindToolType
  6. icon.library/FreeDiskObject
  7. icon.library/FreeFreeList
  8. icon.library/GetDiskObject
  9. icon.library/MatchToolValue
  10. icon.library/PutDiskObject
  11.  
  12.  
  13. icon.library/AddFreeList                               icon.library/AddFreeList
  14.  
  15.    NAME
  16.        AddFreeList - add memory to the free list
  17.  
  18.    SYNOPSIS
  19.        status = AddFreeList( free, mem, len )
  20.        D0                    A0    A1    A2
  21.  
  22.    FUNCTION
  23.        This routine adds the specified memory to the free list.
  24.     The free list will be extended (if required).  If there
  25.     is not enough memory to complete the call, a null is returned.
  26.  
  27.     Note that AddFreeList does NOT allocate the requested memory.
  28.     It only records the memory in the free list.
  29.  
  30.    INPUTS
  31.     free -- a pointer to a FreeList structure
  32.     mem -- the base of the memory to be recorded
  33.     len -- the length of the memory to be recorded
  34.  
  35.    RESULTS
  36.     status -- nonzero if the call succeeded.
  37.  
  38.    EXCEPTIONS
  39.  
  40.    SEE ALSO
  41.     AllocEntry, FreeEntry, FreeFreeList
  42.  
  43.    BUGS
  44.  
  45.  
  46. icon.library/BumpRevision                             icon.library/BumpRevision
  47.  
  48.    NAME
  49.        BumpRevision - reformat a name for a second copy
  50.  
  51.    SYNOPSIS
  52.        result = BumpRevision( newbuf, oldname  )
  53.        D0                     A0      A1
  54.  
  55.    FUNCTION
  56.     BumpRevision takes a name an turns it into a "copy of name".
  57.     It knows how to deal with copies of copies.  The routine
  58.     will truncate the new name to the maximum dos name size
  59.     (currently 30 characters).
  60.  
  61.    INPUTS
  62.     newbuf - the new buffer that will receive the name (it must
  63.         be at least 31 characters long).
  64.     oldname - the original name
  65.  
  66.    RESULTS
  67.     result - a pointer to newbuf
  68.  
  69.    EXCEPTIONS
  70.  
  71.    EXAMPLE
  72.     oldname                 newbuf
  73.     -------                 ------
  74.     "foo"                 "copy of foo"
  75.     "copy of foo"             "copy 2 of foo"
  76.     "copy 2 of foo"             "copy 3 of foo"
  77.     "copy 199 of foo"         "copy 200 of foo"
  78.     "copy foo"             "copy of copy foo"
  79.     "copy 0 of foo"             "copy 1 of foo"
  80.     "012345678901234567890123456789" "copy of 0123456789012345678901"
  81.  
  82.    SEE ALSO
  83.  
  84.    BUGS
  85.  
  86.  
  87. icon.library/FindToolType                             icon.library/FindToolType
  88.  
  89.    NAME
  90.        FindToolType - find the value of a ToolType variable
  91.  
  92.    SYNOPSIS
  93.        value = FindToolType( toolTypeArray, typeName  )
  94.        D0                    A0             A1
  95.  
  96.    FUNCTION
  97.        This function searches a tool type array for a given entry,
  98.     and returns a pointer to that entry.  This is useful for
  99.     finding standard tool type variables.  The returned
  100.     value is not a new copy of the string but is only
  101.     a pointer to the part of the string after typeName.
  102.  
  103.    INPUTS
  104.     toolTypeArray - an array of strings
  105.     typeName - the name of the tooltype entry
  106.  
  107.    RESULTS
  108.     value - a pointer to a string that is the value bound to
  109.         typeName, or NULL if typeName is not in
  110.         the toolTypeArray.
  111.  
  112.    EXCEPTIONS
  113.  
  114.    EXAMPLE
  115.     Assume the tool type array has two strings in it:
  116.         "FILETYPE=text"
  117.         "TEMPDIR=:t"
  118.  
  119.     FindToolType( toolTypeArray, "FILETYPE" ) returns "text"
  120.     FindToolType( toolTypeArray, "TEMPDIR" )  returns ":t"
  121.     FindToolType( toolTypeArray, "MAXSIZE" )  returns NULL
  122.  
  123.    SEE ALSO
  124.     MatchToolValue
  125.  
  126.    BUGS
  127.  
  128.  
  129. icon.library/FreeDiskObject                         icon.library/FreeDiskObject
  130.  
  131.    NAME
  132.        FreeDiskObject - free all memory in a Workbench disk object
  133.  
  134.    SYNOPSIS
  135.        FreeDiskObject( diskobj )
  136.                        A0
  137.  
  138.    FUNCTION
  139.        This routine frees all memory in a Workbench disk object, and the
  140.     object itself.  It is implemented via FreeFreeList().
  141.  
  142.     GetDiskObject() takes care of all the initialization required
  143.     to set up the objects free list.  This procedure may ONLY
  144.     be called on DiskObject allocated via GetDiskObject().
  145.  
  146.    INPUTS
  147.     diskobj -- a pointer to a DiskObject structure
  148.  
  149.    RESULTS
  150.  
  151.    EXCEPTIONS
  152.  
  153.    SEE ALSO
  154.     GetDiskObject, FreeFreeList
  155.  
  156.    BUGS
  157.  
  158.  
  159. icon.library/FreeFreeList                             icon.library/FreeFreeList
  160.  
  161.    NAME
  162.        FreeFreeList - free all memory in a free list
  163.  
  164.    SYNOPSIS
  165.        FreeFreeList( free )
  166.                      A0
  167.  
  168.    FUNCTION
  169.        This routine frees all memory in a free list, and the
  170.     free list itself.  It is useful for easily getting
  171.     rid of all memory in a series of structures.  There is
  172.     a free list in a Workbench object, and this contains
  173.     all the memory associated with that object.
  174.  
  175.     A FreeList is a list of MemList structures.  See the
  176.     MemList and MemEntry documentation for more information.    
  177.  
  178.     If the FreeList itself is in the free list, it must be
  179.     in the first MemList in the FreeList.
  180.  
  181.    INPUTS
  182.     free -- a pointer to a FreeList structure
  183.  
  184.    RESULTS
  185.  
  186.    EXCEPTIONS
  187.  
  188.    SEE ALSO
  189.     AllocEntry, FreeEntry, AddFreeList
  190.  
  191.    BUGS
  192.  
  193.  
  194. icon.library/GetDiskObject                           icon.library/GetDiskObject
  195.  
  196.    NAME
  197.        GetDiskObject - read in a Workbench disk object
  198.  
  199.    SYNOPSIS
  200.        diskobj = GetDiskObject( name )
  201.        D0                       A0
  202.  
  203.    FUNCTION
  204.        This routine reads in a Workbench disk object in from disk.  The
  205.     name parameter will have a ".info" postpended to it, and the
  206.     info file of that name will be read.  If the call fails,
  207.     it will return zero.  The reason for the failure may be obtained
  208.     via IoErr().
  209.  
  210.     Using this routine protects you from any future changes to
  211.     the way icons are stored within the system.
  212.  
  213.     A FreeList structure is allocated just after the DiskObject
  214.     structure; FreeDiskObject makes use of this to get rid of the
  215.     memory that was allocated.
  216.  
  217.    INPUTS
  218.     name -- name of the object
  219.  
  220.    RESULTS
  221.     diskobj -- the Workbench disk object in question
  222.  
  223.    EXCEPTIONS
  224.  
  225.    SEE ALSO
  226.     FreeDiskObject
  227.  
  228.    BUGS
  229.  
  230.  
  231. icon.library/MatchToolValue                         icon.library/MatchToolValue
  232.  
  233.    NAME
  234.        MatchToolValue - check a tool type variable for a particular value
  235.  
  236.    SYNOPSIS
  237.        result = MatchToolValue( typeString, value  )
  238.        D0                       A0          A1
  239.  
  240.    FUNCTION
  241.     MatchToolValue is useful for parsing a tool type value for
  242.     a known value.  It knows how to parse the syntax for a tool
  243.     type value (in particular, it knows that '|' separates
  244.     alternate values).
  245.  
  246.    INPUTS
  247.     typeString - a ToolType value (as returned by FindToolType)
  248.     value - you are interested if value appears in typeString
  249.  
  250.    RESULTS
  251.     result - a one if the value was in typeString
  252.  
  253.    EXCEPTIONS
  254.  
  255.    EXAMPLE
  256.     Assume there are two type strings:
  257.         type1 = "text"
  258.         type2 = "a|b|c"
  259.  
  260.     MatchToolValue( type1, "text" ) returns 1
  261.     MatchToolValue( type1, "data" ) returns 0
  262.     MatchToolValue( type2, "a" ) returns 1
  263.     MatchToolValue( type2, "b" ) returns 1
  264.     MatchToolValue( type2, "d" ) returns 0
  265.     MatchToolValue( type2, "a|b" ) returns 0
  266.  
  267.    SEE ALSO
  268.     FindToolType
  269.  
  270.    BUGS
  271.  
  272.  
  273. icon.library/PutDiskObject                           icon.library/PutDiskObject
  274.  
  275.    NAME
  276.        PutDiskObject - write out a DiskObject to disk
  277.  
  278.    SYNOPSIS
  279.        status = PutDiskObject( name, diskobj )
  280.        D0                      A0    A1
  281.  
  282.    FUNCTION
  283.        This routine writes out a DiskObject structure, and its
  284.     associated information.  The file name of the info
  285.     file will be the name parameter with a
  286.     ".info" postpended to it.  If the call fails, a zero will
  287.     be returned.  The reason for the failure may be obtained
  288.     via IoErr().
  289.  
  290.     Using this routine protects you from any future changes to
  291.     the way icons are stored within the system.
  292.  
  293.    INPUTS
  294.     name -- name of the object
  295.     diskobj -- a pointer to a DiskObject
  296.  
  297.    RESULTS
  298.     status -- non-zero if the call succeeded
  299.  
  300.    EXCEPTIONS
  301.  
  302.    SEE ALSO
  303.     GetDiskObject, FreeDiskObject
  304.  
  305.    BUGS
  306.  
  307.